home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.5 Applications 1999 May / SGI IRIX 6.5 Applications 1999 May.iso / dist / arraysvcs.idb / usr / share / catman / p_man / cat3x / asparseopts.z.z / asparseopts.z / asparseopts
Text File  |  1998-10-27  |  20KB  |  331 lines
  1.  
  2.  
  3.  
  4. aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))                                                aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      asparseopts - parse standard array services command line options
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<aaaarrrrrrrraaaayyyyssssvvvvccccssss....hhhh>>>>
  13.  
  14.      aaaassssooooppppttttiiiinnnnffffoooo____tttt ****aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((iiiinnnntttt aaaarrrrggggcccc,,,, cccchhhhaaaarrrr ********aaaarrrrggggvvvv,,,, iiiinnnntttt SSSSeeeelllleeeecccctttt,,,, iiiinnnntttt CCCCoooonnnnttttrrrroooollll))));;;;
  15.  
  16. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  17.      The _a_s_p_a_r_s_e_o_p_t_s function is used to parse standard array services command
  18.      line options from a list of strings, presumably the list of arguments to
  19.      an array services client program.  The results are returned in the form
  20.      of as aaaassssooooppppttttiiiinnnnffffoooo____tttt structure, which contains parsed, validated values for
  21.      the options specified in the argument list, as well as a list of the
  22.      arguments that were not recognized as one of the selected array services
  23.      options.
  24.  
  25.      The aaaarrrrggggcccc and aaaarrrrggggvvvv arguments are an argument count and argument list, in
  26.      the form typically provided to the function mmmmaaaaiiiinnnn of an ordinary C
  27.      program.
  28.  
  29.      The SSSSeeeelllleeeecccctttt argument is used to specify which of the "standard" array
  30.      service command line options are to be included in this operation.  It is
  31.      formed from the logical OR of one or more of the following flags, which
  32.      are defined in <<<<aaaarrrrrrrraaaayyyyssssvvvvccccssss....hhhh>>>>:
  33.  
  34.      _AAAA_SSSS_OOOO_IIII_VVVV______AAAA_RRRR_RRRR_AAAA_YYYY
  35.             Parse the ----aaaarrrrrrrraaaayyyy option, which takes the name of an array as a
  36.             subargument.  ----aaaa is a synonym for the ----aaaarrrrrrrraaaayyyy option.
  37.  
  38.      _AAAA_SSSS_OOOO_IIII_VVVV______AAAA_SSSS_HHHH
  39.             Parse the ----aaaasssshhhh option, which takes an array session handle as a
  40.             subargument.  The array session handle may be specified in
  41.             decimal, octal (if preceded by "0") or hexadecimal (if preceded by
  42.             "0x").  ----hhhh and ----aaaarrrrsssseeeessssssss are both synonyms for the ----aaaasssshhhh option.
  43.  
  44.      _AAAA_SSSS_OOOO_IIII_VVVV______CCCC_OOOO_NNNN_NNNN_EEEE_CCCC_TTTT_TTTT_OOOO
  45.             Parse the ----ccccoooonnnnnnnneeeeccccttttttttoooo option, which takes a connection timeout
  46.             value as a subargument.  The value must be specified in decimal
  47.             only.  ----CCCC is a synonym for the ----ccccoooonnnnnnnneeeeccccttttttttoooo option.
  48.  
  49.      _AAAA_SSSS_OOOO_IIII_VVVV______FFFF_OOOO_RRRR_WWWW_AAAA_RRRR_DDDD
  50.             Parses the ----ffffoooorrrrwwwwaaaarrrrdddd and ----ddddiiiirrrreeeecccctttt options, which specify the array
  51.             services forwarding mode; ----ffffoooorrrrwwwwaaaarrrrdddd indicates that array services
  52.             commands should be forwarded to their ultimate destination via the
  53.             server on the local machine, while ----ddddiiiirrrreeeecccctttt means that array
  54.             services commands should be sent directly to the remote server.
  55.             ----FFFF is a synonym for the ----ffffoooorrrrwwwwaaaarrrrdddd option and ----DDDD is a synonym for
  56.             the ----ddddiiiirrrreeeecccctttt option.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))                                                aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))
  71.  
  72.  
  73.  
  74.      _AAAA_SSSS_OOOO_IIII_VVVV______LLLL_CCCC_LLLL_KKKK_EEEE_YYYY
  75.             Parse the ----llllooooccccaaaallllkkkkeeeeyyyy option, which takes the authentication key for
  76.             the local machine as a subargument.  ----KKKKllll is a synonym for the
  77.             ----llllooooccccaaaallllkkkkeeeeyyyy option.
  78.  
  79.      _AAAA_SSSS_OOOO_IIII_VVVV______LLLL_OOOO_CCCC_AAAA_LLLL
  80.             Parse the ----llllooooccccaaaallll option, which indicates that an array services
  81.             function should take place only on the local server, as opposed to
  82.             being broadcast to all of the servers in an array, for example.
  83.             ----llll is a synonym for the ----llllooooccccaaaallll option.
  84.  
  85.      _AAAA_SSSS_OOOO_IIII_VVVV______PPPP_IIII_DDDD
  86.             Parse the ----ppppiiiidddd option, which takes a process ID as a subargument.
  87.             The process ID should be specified in decimal only and must be
  88.             positive.  ----iiii and ----pppprrrroooocccceeeessssssss are both synonyms for the ----ppppiiiidddd option.
  89.  
  90.      _AAAA_SSSS_OOOO_IIII_VVVV______PPPP_OOOO_RRRR_TTTT_NNNN_UUUU_MMMM
  91.             Parse the ----ppppoooorrrrttttnnnnuuuummmm option, which takes a port number as a
  92.             subargument.  The port number should be specified in decimal only
  93.             and must be in the range 1-65535.  ----pppp is a synonym for the
  94.             ----ppppoooorrrrttttnnnnuuuummmm option.
  95.  
  96.      _AAAA_SSSS_OOOO_IIII_VVVV______RRRR_EEEE_MMMM_KKKK_EEEE_YYYY
  97.             Parse the ----rrrreeeemmmmooootttteeeekkkkeeeeyyyy option, which takes the authentication key
  98.             for a remote machine as a subargument.  ----KKKKrrrr is a synonym for the
  99.             ----rrrreeeemmmmooootttteeeekkkkeeeeyyyy option.
  100.  
  101.      _AAAA_SSSS_OOOO_IIII_VVVV______SSSS_EEEE_RRRR_VVVV_EEEE_RRRR
  102.             Parse the ----sssseeeerrrrvvvveeeerrrr option, which takes the hostname of an array
  103.             daemon as a subargument.  ----ssss is a synonym for the ----sssseeeerrrrvvvveeeerrrr option.
  104.  
  105.      _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_IIII_MMMM_EEEE_OOOO_UUUU_TTTT
  106.             Parse the ----ttttiiiimmmmeeeeoooouuuutttt option, which takes a timeout value as a
  107.             subargument.  The value must be specified in decimal only.  ----tttt is
  108.             a synonym for the ----ttttiiiimmmmeeeeoooouuuutttt option.
  109.  
  110.      _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN
  111.             If this flag is specified and no invalid arguments were
  112.             encountered (in other words, the iiiinnnnvvvvaaaalllliiiidddd member of the returned
  113.             asoptinfo_t is 0), then a server token using the parsed options
  114.             will be created using _a_s_o_p_e_n_s_e_r_v_e_r__f_r_o_m__o_p_t_i_n_f_o(3X).
  115.  
  116.      _AAAA_SSSS_OOOO_IIII_VVVV______VVVV_EEEE_RRRR_BBBB_OOOO_SSSS_EEEE
  117.             Parse the ----vvvv option, which is used to set a verbosity level.  The
  118.             default verbose level is 0, and each occurrence of ----vvvv will
  119.             increase the level by 1.  If an option begins with "v" and is
  120.             followed by any number of other non-whitespace characters (for
  121.             example, "-vvv"), then the verbose level is increased by the
  122.             number of characters following the hyphen (3 in the case of
  123.             "-vvv").
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))                                                aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))
  137.  
  138.  
  139.  
  140.      The CCCCoooonnnnnnnneeeecccctttt argument is used to specify flags which modify the parsing
  141.      behavior.  It is formed from the logical OR of zero or more of the
  142.      following flags, which are defined in <<<<aaaarrrrrrrraaaayyyyssssvvvvccccssss....hhhh>>>>:
  143.  
  144.      _AAAA_SSSS_OOOO_IIII_CCCC______LLLL_OOOO_GGGG_EEEE_RRRR_RRRR_SSSS
  145.             Specifies that syntax errors and other abnormal conditions should
  146.             be reported to the normal array services error logging
  147.             destination, which is typically _s_t_d_e_r_r.  If this flag is not
  148.             specified no error messages will be generated, but the iiiinnnnvvvvaaaalllliiiidddd
  149.             member of the returned asoptinfo_t can still be checked to
  150.             determine if any errors were detected.
  151.  
  152.      _AAAA_SSSS_OOOO_IIII_CCCC______NNNN_OOOO_DDDD_UUUU_PPPP_SSSS
  153.             Ordinarily, if an option is specified more than once, the last
  154.             occurrence of the option in the argument list will quietly
  155.             override any previous occurrences of the option.  If the
  156.             ASOIC_NODUPS flag is specified, then duplicate occurrences will be
  157.             called out as errors and the option will be marked as invalid in
  158.             the returned asoptinfo_t.
  159.  
  160.      _AAAA_SSSS_OOOO_IIII_CCCC______OOOO_PPPP_TTTT_SSSS_OOOO_NNNN_LLLL_YYYY
  161.             This flag causes parsing to stop as soon as an argument which does
  162.             not begin with a "-" character is encountered (not including
  163.             subarguments to valid options).  The "non-option" argument and all
  164.             arguments following it will be returned as unrecognized arguments,
  165.             even if some of the subsequent arguments would otherwise have been
  166.             valid array services options.
  167.  
  168.      _AAAA_SSSS_OOOO_IIII_CCCC______SSSS_EEEE_LLLL_OOOO_NNNN_LLLL_YYYY
  169.             This is similar to _AAAA_SSSS_OOOO_IIII_CCCC______OOOO_PPPP_TTTT_SSSS_OOOO_NNNN_LLLL_YYYY with the added restriction that
  170.             parsing stops as soon as _a_n_y argument which is not a selected
  171.             option or the subargument of a selected option is encountered.
  172.  
  173.      If the argument list is successfully parsed, a pointer to an aaaassssooooppppttttiiiinnnnffffoooo____tttt
  174.      structure (also defined in <<<<aaaarrrrrrrraaaayyyyssssvvvvccccssss....hhhh>>>>) is returned.  The storage for
  175.      this structure is allocated using _m_a_l_l_o_c(3C) and can be released using
  176.      the _a_s_f_r_e_e_o_p_t_i_n_f_o(3X) function.  An aaaassssooooppppttttiiiinnnnffffoooo____tttt structure looks similar
  177.      to this:
  178.  
  179.                typedef struct asoptinfo {
  180.                        int        argc;
  181.                        char       **argv;
  182.                        int        valid;
  183.                        int        invalid;
  184.                        int        options;
  185.                        asserver_t token;
  186.                        char       *server;
  187.                        char       *array;
  188.                        askey_t    localkey;
  189.                        askey_t    remotekey;
  190.                        ash_t      ash;
  191.                        pid_t      pid;
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))                                                aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))
  203.  
  204.  
  205.  
  206.                        int        portnum;
  207.                        int        timeout;
  208.                        int        connectto;
  209.                        int        verbose;
  210.                } asoptinfo_t;
  211.  
  212.  
  213.      The aaaarrrrggggcccc and aaaarrrrggggvvvv members are a count and list, respectively, of
  214.      arguments that were not recognized as selected array services options or
  215.      their corresponding subarguments.
  216.  
  217.      The vvvvaaaalllliiiidddd member is a bitmap used to specify which options were
  218.      successfully parsed and are present in the asoptinfo_t.  The same flags
  219.      used to specify the SSSSeeeelllleeeecccctttt argument to _a_s_p_a_r_s_e_o_p_t_s are used to indicate
  220.      which options are present.
  221.  
  222.      The iiiinnnnvvvvaaaalllliiiidddd member is a bitmap of options that were selected and
  223.      specified in the argument list, but had values which were invalid in some
  224.      way.  If the _AAAA_SSSS_OOOO_IIII_CCCC______LLLL_OOOO_GGGG_EEEE_RRRR_RRRR_SSSS control flag was specified, then an error
  225.      message explaining the nature of the problem should already have been
  226.      generated.  This member also uses the same flags as vvvvaaaalllliiiidddd and SSSSeeeelllleeeecccctttt.
  227.  
  228.      The ooooppppttttiiiioooonnnnssss member is a bitmap of flags indicating the state of the
  229.      various binary options.  These include:
  230.  
  231.      ASOIO_FORWARD
  232.             If set, command forwarding has been requested.  Otherwise, a
  233.             direct connection is desired.
  234.  
  235.      ASOIO_LOCAL
  236.             If set, the command should be restricted to the local server.
  237.             Otherwise, it may be considered eligible for broadcast to all
  238.             servers in an array.
  239.  
  240.      IMPORTANT:  A flag in ooooppppttttiiiioooonnnnssss should only be examined if it is also
  241.      marked as valid in vvvvaaaalllliiiidddd.  For example, the state of the _AAAA_SSSS_OOOO_IIII_OOOO______FFFF_OOOO_RRRR_WWWW_AAAA_RRRR_DDDD
  242.      flag in ooooppppttttiiiioooonnnnssss is only meaningful if the _AAAA_SSSS_OOOO_IIII_VVVV______FFFF_OOOO_RRRR_WWWW_AAAA_RRRR_DDDD flag is set in
  243.      vvvvaaaalllliiiidddd.  If the appropriate flag in vvvvaaaalllliiiidddd is _n_o_t set, then the option
  244.      should be considered unspecified and a default setting should be used
  245.      instead.
  246.  
  247.      The ttttooookkkkeeeennnn member of aaaassssooooppppttttiiiinnnnffffoooo____tttt is not a value directly parsed from the
  248.      argument list, but instead a server token created using the values that
  249.      were successfully parsed from the argument list.  It will only be created
  250.      if the _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN flag was set in SSSSeeeelllleeeecccctttt.  If it is successfully
  251.      created, the _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN flag will be set in the vvvvaaaalllliiiidddd member of the
  252.      aaaassssooooppppttttiiiinnnnffffoooo____tttt.  Otherwise, _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN will be set in the iiiinnnnvvvvaaaalllliiiidddd member
  253.      and _a_s_e_r_r_o_r_c_o_d_e(3X) will be set accordingly.
  254.  
  255.      The remaining members of the aaaassssooooppppttttiiiinnnnffffoooo____tttt contain the values of the
  256.      selected array services options.  If a selected option was specified in
  257.      the argument list, then its flag in vvvvaaaalllliiiidddd will be set and the
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))                                                aaaassssppppaaaarrrrsssseeeeooooppppttttssss((((3333xxxx))))
  269.  
  270.  
  271.  
  272.      corresponding member of aaaassssooooppppttttiiiinnnnffffoooo____tttt will contain the parsed value of that
  273.      option.  If a selected option was _n_o_t specified in the argument list,
  274.      then its flag in vvvvaaaalllliiiidddd will not be set and the corresponding member of
  275.      aaaassssooooppppttttiiiinnnnffffoooo____tttt will contain a default value (generally NULL, 0 or -1, as
  276.      appropriate).  If a selected option had an invalid value, then its flag
  277.      will be set in iiiinnnnvvvvaaaalllliiiidddd and the contents of the corresponding member of
  278.      aaaassssooooppppttttiiiinnnnffffoooo____tttt are unpredictable.
  279.  
  280. NNNNOOOOTTTTEEEESSSS
  281.      _a_s_p_a_r_s_e_o_p_t_s is found in the library "libarray.so", and will be loaded if
  282.      the option "-larray" is used with _c_c(1) or _l_d(1).
  283.  
  284. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  285.      aserrorcode(3X), asfreeoptinfo(3X), asopenserver_from_optinfo(3X),
  286.  
  287. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  288.      If successful, _a_s_p_a_r_s_e_o_p_t_s returns a pointer to an aaaassssooooppppttttiiiinnnnffffoooo____tttt structure.
  289.      If a severe error occurs, NULL is returned and _a_s_e_r_r_o_r_c_o_d_e is set
  290.      appropriately.  If _a_s_p_a_r_s_e_o_p_t_s is successful and the _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN flag of
  291.      SSSSeeeelllleeeecccctttt was specified but a server token could not be created, the pointer
  292.      to the aaaassssooooppppttttiiiinnnnffffoooo____tttt will be returned as usual, but the _AAAA_SSSS_OOOO_IIII_VVVV______TTTT_OOOO_KKKK_EEEE_NNNN flag of
  293.      the iiiinnnnvvvvaaaalllliiiidddd member will be set and _a_s_e_r_r_o_r_c_o_d_e will contain the error
  294.      returned by _a_s_o_p_e_n_s_e_r_v_e_r__f_r_o_m__o_p_t_i_n_f_o(3X).
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.